GitLab CI Syntax and Variables Guide

I have recently started researching GitLab CI again. Although this work has been ongoing for a while, the intermittent nature of my study often leads me to look up the purpose of certain syntax repeatedly. I decided to have Claude help me organize some common syntax for easy reference in the future.

Basic Structure

The GitLab CI configuration file is .gitlab-ci.yml, which defines the tasks your project should execute in the GitLab CI pipeline.

General file naming conventions:

Main CI/CD configuration file: .gitlab-ci.yml (fixed name).
Included files (includes): Usually follow the .gitlab-ci-*.yml format, for example:
- .gitlab-ci-deploy.yml
- .gitlab-ci-build.yml
- .gitlab-ci-test.yml

Stages

Stages define the order in which jobs are executed:

yaml

stages:
  - build
  - test
  - deploy

All jobs within a stage run in parallel, and all must succeed before moving to the next stage.

Common stage names (in order of execution):

build - Build phase.
test - Testing phase.
quality - Code quality checks.
security - Security checks.
publish - Publish to registry.
deploy - Deploy to environment.
notify - Notifications.
cleanup - Resource cleanup.

Jobs

Jobs are the units that actually perform the work:

yaml

build-job:
  stage: build
  script:
    - echo "Building the app..."
    - mkdir build
    - cd build
    - cmake ..

Naming conventions: Jobs usually follow the "action-object-environment" pattern, for example:

build-app
test-api
deploy-staging

Rules

Rules define the conditions under which a job is executed:

yaml

test-job:
  stage: test
  script:
    - echo "Running tests..."
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"
      when: always
    - when: never

Rules are evaluated in order. When a rule matches, the when value of that rule is applied to determine whether the job runs.

Only/Except

This is older syntax but still valid; it restricts job execution based on branches or tags:

yaml

deploy-job:
  stage: deploy
  script:
    - echo "Deploying application..."
  only:
    - main
    - tags

TIP

GitLab officially recommends using rules instead of only/except because rules provides more flexibility and control. The equivalent rules implementation is as follows:

yaml

deploy-job:
  stage: deploy
  script:
    - echo "Deploying application..."
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: always
    - if: $CI_COMMIT_TAG
      when: always
    - when: never

Variables

You can define global or job-specific variables:

yaml

variables:
  GLOBAL_VAR: "global value"

test-job:
  variables:
    JOB_SPECIFIC_VAR: "job specific value"
  script:
    - echo $GLOBAL_VAR
    - echo $JOB_SPECIFIC_VAR

Naming conventions: Variables are typically uppercase with underscores, for example:

APP_VERSION
DOCKER_IMAGE_NAME
DATABASE_URL

TIP

When using variables in GitLab CI, you can use the $VARIABLE_NAME or ${VARIABLE_NAME} syntax. When a variable name needs to be concatenated with other text, use the brace syntax ${VARIABLE_NAME} to clearly define the scope of the variable name and avoid parsing errors.

Before Script / After Script

Scripts to be executed before and after a job runs:

yaml

default:
  before_script:
    - echo "Before script section"
  after_script:
    - echo "After script section"

job1:
  script:
    - echo "My script"

Cache

Used to store and reuse files between builds:

yaml

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .npm/

Naming conventions: Cache keys usually use a combination of variables:

${CI_COMMIT_REF_SLUG} - Based on branch.
${CI_JOB_NAME}-${CI_COMMIT_REF_SLUG} - Based on job and branch.

Artifacts

Files generated after jobs complete, which can be downloaded or used by subsequent jobs:

yaml

build-job:
  stage: build
  script:
    - echo "Creating artifacts..."
    - mkdir -p build/
    - touch build/info.txt
  artifacts:
    paths:
      - build/
    expire_in: 1 week

Dependencies

Defines which jobs' artifacts a job uses:

yaml

test-job:
  stage: test
  dependencies:
    - build-job
  script:
    - echo "Testing with artifacts from build-job"

Workflow

Workflow controls the execution conditions of the entire pipeline. Unlike job-level rules, workflow:rules determines whether the entire pipeline should be created. If no rules match or all rules evaluate to when:never, the entire pipeline will not run.

Basic Syntax

yaml

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: always
    - if: $CI_MERGE_REQUEST_IID
      when: always
    - if: $CI_COMMIT_TAG
      when: always
    - when: never

Meaning of the example above:

Run the pipeline whenever there is a commit to the main branch.
Run the pipeline whenever there is a merge request.
Run the pipeline whenever there is a tag.
Do not run the pipeline in other cases.

Naming the Pipeline

You can assign a name to the pipeline, which is displayed in the GitLab interface:

yaml

workflow:
  name: "Main Pipeline"

You can also use variables in the name:

yaml

workflow:
  name: "$CI_COMMIT_REF_NAME Deployment"

Rule Conditions

Workflow rules support the same conditions as job rules:

yaml

workflow:
  rules:
    # Run only on scheduled pipelines
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: always

    # Run only on pushes to specific branches
    - if: $CI_COMMIT_BRANCH == "release/*"
      when: always

    # Run based on file changes
    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_TITLE =~ /docs:/
      changes:
        - docs/**/*
      when: always

    # Run when the configuration file itself is modified
    - changes:
      - .gitlab-ci.yml
      when: always

    # Set variables
    - if: $CI_COMMIT_BRANCH == "develop"
      variables:
        IS_DEVELOPMENT: "true"
      when: always

    # Default case
    - when: never

Practical Examples

Decide whether to run the pipeline based on the commit message:

yaml

workflow:
  rules:
    - if: $CI_COMMIT_TITLE =~ /\[skip ci\]/
      when: never
    - if: $CI_COMMIT_TITLE =~ /\[run ci\]/
      when: always
    - when: on_success

Run different pipelines based on project path changes:

yaml

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - frontend/**/*
      variables:
        PIPELINE_TYPE: "frontend"
      when: always
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - backend/**/*
      variables:
        PIPELINE_TYPE: "backend"
      when: always
    - when: never

Automatically run the pipeline only during working hours:

yaml

workflow:
  rules:
    # Working days (Monday to Friday)
    - if: $CI_PIPELINE_SOURCE == "schedule" && $CI_COMMIT_BRANCH == "main"
      when: always
    # Working hours (9:00 - 18:00)
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main" && $HOUR >= 9 && $HOUR < 18
      when: always
    # Manual trigger required outside working hours
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
      allow_failure: true
    - when: never

Notes

workflow:rules is global and affects the entire pipeline.
If workflow:rules is not set, GitLab uses default rules, meaning all pushes and merge requests trigger a pipeline.
When using when:never in workflow:rules, the entire pipeline will not execute, rather than just skipping the rule.
Workflow rules are evaluated in order; once a matching rule is found, evaluation stops.
Variables set in the workflow can be accessed by all jobs.

Needs

Allows a job to run immediately after specified jobs complete, without waiting for the entire stage to finish:

yaml

job2:
  stage: test
  needs:
    - job1
  script:
    - echo "This job runs after job1, even if they're in the same stage"

Services

Defines an additional Docker container, typically used to provide services like databases:

yaml

test:
  services:
    - postgres:13
  script:
    - echo "Testing with Postgres service"

Includes

Imports configuration from other files:

yaml

include:
  - local: '/templates/ci-template.yml'
  - project: 'my-group/my-project'
    file: '/templates/ci-template.yml'
  - template: Auto-DevOps.gitlab-ci.yml

Templates

Uses YAML anchors and aliases to create reusable templates:

yaml

# Define template (jobs starting with a dot are not executed)
.build_template: &build_definition
  stage: build
  script:
    - echo "Building using template"
  tags:
    - docker

# Use template
build_job1:
  <<: *build_definition
  script:
    - echo "Building job 1"
    - make build

# Extend template
build_job2:
  <<: *build_definition
  script:
    - echo "Building job 2"
    - make special-build
  variables:
    BUILD_TYPE: "special"

Naming conventions:

Template job names start with a dot, e.g., .build_template.
Template anchors usually use _definition or _template suffixes.

Predefined Environment Variables List

The following content is excerpted from the Predefined CI/CD variables reference. I used Claude to help translate it into Chinese for my own reference.

Scope Description

Scope	Description
Pre-pipeline	Variables that exist before the pipeline is created; available to all jobs.
Pipeline	Variables generated after the pipeline is created; available to all jobs.
Job-only	Variables available only in the execution environment of a specific job.

ChatOps and Basic CI Variables

Variable	Scope	Description
CHAT_CHANNEL	Pipeline	The chat channel that triggered the ChatOps command.
CHAT_INPUT	Pipeline	Additional parameters passed with the ChatOps command.
CHAT_USER_ID	Pipeline	The user ID of the user who triggered the ChatOps command in the chat service.
CI	Pre-pipeline	Available in all CI/CD jobs. Set to true when available.
CI_API_V4_URL	Pre-pipeline	GitLab API v4 root URL.
CI_API_GRAPHQL_URL	Pre-pipeline	GitLab API GraphQL root URL. Introduced in GitLab 15.11.
CI_DEBUG_TRACE	Pipeline	true if debug logging (tracing) is enabled.
CI_DEBUG_SERVICES	Pipeline	true if service container logging is enabled. Introduced in GitLab 15.7. Requires GitLab Runner 15.7.
GITLAB_CI	Pre-pipeline	Available in all CI/CD jobs. Set to true when available.
GITLAB_FEATURES	Pre-pipeline	Comma-separated list of licensed features available to the GitLab instance and license.

Variable	Scope	Description
CI_BUILDS_DIR	Job-only	The top-level directory where builds are executed.
CI_COMMIT_AUTHOR	Pre-pipeline	The author of the commit, in the format Name <email>.
CI_COMMIT_BEFORE_SHA	Pre-pipeline	The previous latest commit on the branch or tag. Always 0000000000000000000000000000000000000000 for merge request pipelines, scheduled pipelines, the first commit of a branch or tag, or manual pipelines.
CI_COMMIT_BRANCH	Pre-pipeline	The commit branch name. Available in branch pipelines, including default branch pipelines. Not available in merge request or tag pipelines.
CI_COMMIT_DESCRIPTION	Pre-pipeline	The commit description. If the title is less than 100 characters, it is the message excluding the first line.
CI_COMMIT_MESSAGE	Pre-pipeline	The full commit message.
CI_COMMIT_REF_NAME	Pre-pipeline	The branch or tag name for which the project is built.
CI_COMMIT_REF_PROTECTED	Pre-pipeline	true if the job is running for a protected reference, false otherwise.
CI_COMMIT_REF_SLUG	Pre-pipeline	Lowercase version of CI_COMMIT_REF_NAME, truncated to 63 bytes, with all characters except 0-9 and a-z replaced by -. No leading/trailing -. Used for URLs, hostnames, and domain names.
CI_COMMIT_SHA	Pre-pipeline	The commit revision for which the project is built.
CI_COMMIT_SHORT_SHA	Pre-pipeline	The first eight characters of CI_COMMIT_SHA.
CI_COMMIT_TAG	Pre-pipeline	The commit tag name. Available only in tag pipelines.
CI_COMMIT_TAG_MESSAGE	Pre-pipeline	The commit tag message. Available only in tag pipelines. Introduced in GitLab 15.5.
CI_COMMIT_TIMESTAMP	Pre-pipeline	The commit timestamp in ISO 8601 format. For example, 2022-01-31T16:47:55Z. Defaults to UTC.
CI_COMMIT_TITLE	Pre-pipeline	The commit title. The full first line of the message.
CI_OPEN_MERGE_REQUESTS	Pre-pipeline	Comma-separated list of up to four merge requests using the current branch and project as the source. Available only in branch and merge request pipelines if the branch has associated merge requests. For example, gitlab-org/gitlab!333,gitlab-org/gitlab-foss!11.

Variable	Scope	Description
CI_CONFIG_PATH	Pre-pipeline	Path to the CI/CD configuration file. Defaults to .gitlab-ci.yml.
CI_CONCURRENT_ID	Job-only	Unique ID for build execution in a single runner.
CI_CONCURRENT_PROJECT_ID	Job-only	Unique ID for build execution in a single runner and project.
CI_DEFAULT_BRANCH	Pre-pipeline	The project's default branch name.
CI_PROJECT_DIR	Job-only	The full path where the repository is cloned and the job is executed. If the GitLab Runner builds_dir parameter is set, this variable is relative to that value. See advanced GitLab Runner configuration for more info.
CI_REPOSITORY_URL	Job-only	The full path to clone the repository (HTTP) using the CI/CD job token, in the format https://gitlab-ci-token:[email protected]/my-group/my-project.git.

Variable	Scope	Description
CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX	Pre-pipeline	Direct group image prefix for pulling images through the dependency proxy.
CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX	Pre-pipeline	Top-level group image prefix for pulling images through the dependency proxy.
CI_DEPENDENCY_PROXY_PASSWORD	Pipeline	Password for pulling images through the dependency proxy.
CI_DEPENDENCY_PROXY_SERVER	Pre-pipeline	Server for logging into the dependency proxy. This variable is equivalent to $CI_SERVER_HOST:$CI_SERVER_PORT.
CI_DEPENDENCY_PROXY_USER	Pipeline	Username for pulling images through the dependency proxy.

Variable	Scope	Description
CI_DEPLOY_FREEZE	Pre-pipeline	Available only if the pipeline runs during a deployment freeze window. true when available.
CI_DEPLOY_PASSWORD	Job-only	Authentication password for the GitLab Deploy Token, if the project has one.
CI_DEPLOY_USER	Job-only	Authentication username for the GitLab Deploy Token, if the project has one.
CI_DISPOSABLE_ENVIRONMENT	Pipeline	Available only if the job runs in a disposable environment (environments created only for this job and destroyed after execution - all executors except shell and ssh). true when available.
CI_ENVIRONMENT_NAME	Pipeline	The environment name for this job. Available if environment:name is set.
CI_ENVIRONMENT_SLUG	Pipeline	A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. Available if environment:name is set. The slug is truncated to 24 characters. For uppercase environment names, a random suffix is automatically added.
CI_ENVIRONMENT_URL	Pipeline	The environment URL for this job. Available if environment:url is set.
CI_ENVIRONMENT_ACTION	Pipeline	The action note specified for this job's environment. Available if environment:action is set. Can be start, prepare, or stop.
CI_ENVIRONMENT_TIER	Pipeline	The deployment tier for this job's environment.
CI_KUBERNETES_ACTIVE	Pre-pipeline	Available only if the pipeline has a Kubernetes cluster available for deployment. true when available.
CI_RELEASE_DESCRIPTION	Pipeline	The release description. Available only in tag pipelines. Description length is limited to the first 1024 characters. Introduced in GitLab 15.5.
KUBECONFIG	Pipeline	Path to the kubeconfig file containing environment settings for each shared agent connection. Available only if the GitLab agent is authorized to access the project.

Variable	Scope	Description
CI_GITLAB_FIPS_MODE	Pre-pipeline	Available only if FIPS mode is enabled in the GitLab instance. true when available.
CI_HAS_OPEN_REQUIREMENTS	Pipeline	Available only if the pipeline's project has open requirements. true when available.
CI_JOB_GROUP_NAME	Pipeline	Shared name for job groups when using parallel or manual grouped jobs. For example, if the job name is rspec:test: [ruby, ubuntu], CI_JOB_GROUP_NAME is rspec:test. Otherwise, it is the same as CI_JOB_NAME. Introduced in GitLab 17.10.
CI_JOB_ID	Job-only	The internal ID of the job, unique across all jobs in the GitLab instance.
CI_JOB_IMAGE	Pipeline	The Docker image name used to execute the job.
CI_JOB_MANUAL	Pipeline	Available only if the job was started manually. true when available.
CI_JOB_NAME	Pipeline	The name of the job.
CI_JOB_NAME_SLUG	Pipeline	Lowercase version of CI_JOB_NAME, truncated to 63 bytes, with all characters except 0-9 and a-z replaced by -. No leading/trailing -. Used for paths. Introduced in GitLab 15.4.
CI_JOB_STAGE	Pipeline	The stage name of the job.
CI_JOB_STATUS	Job-only	The status of the job while each runner stage is executing. Used with after_script. Can be success, failed, or canceled.
CI_JOB_TIMEOUT	Job-only	Job timeout in seconds. Introduced in GitLab 15.7. Requires GitLab Runner 15.7.
CI_JOB_TOKEN	Job-only	Token used to authenticate certain API endpoints. The token is valid during the job execution.
CI_JOB_URL	Job-only	Job details URL.
CI_JOB_STARTED_AT	Job-only	The date and time the job started, in ISO 8601 format. For example, 2022-01-31T16:47:55Z. Defaults to UTC.
CI_NODE_INDEX	Pipeline	The index of the job in the job set. Available only when the job uses parallel.
CI_NODE_TOTAL	Pipeline	The total number of instances the job is running in parallel. If the job does not use parallel, it is set to 1.

Variable	Scope	Description
CI_PAGES_DOMAIN	Pre-pipeline	The instance domain hosting GitLab Pages, excluding the namespace subdomain. To use the full hostname, use CI_PAGES_HOSTNAME.
CI_PAGES_HOSTNAME	Job-only	The full hostname where Pages are deployed.
CI_PAGES_URL	Job-only	The URL of the GitLab Pages site. Always a subdomain of CI_PAGES_DOMAIN. In GitLab 17.9 and later, when path_prefix is specified, the value includes the path_prefix.

Variable	Scope	Description
CI_PIPELINE_ID	Job-only	The instance-level ID of the current pipeline. This ID is unique across all projects in the GitLab instance.
CI_PIPELINE_IID	Pipeline	The project-level IID (internal ID) of the current pipeline. This ID is unique only within the current project.
CI_PIPELINE_SOURCE	Pre-pipeline	The trigger method of the pipeline. The value can be one of the pipeline sources.
CI_PIPELINE_TRIGGERED	Pipeline	true if the job was triggered.
CI_PIPELINE_URL	Job-only	Pipeline details URL.
CI_PIPELINE_CREATED_AT	Pre-pipeline	The date and time the pipeline was created, in ISO 8601 format. For example, 2022-01-31T16:47:55Z. Defaults to UTC.
CI_PIPELINE_NAME	Pre-pipeline	The pipeline name defined in workflow:name. Introduced in GitLab 16.3.
CI_PIPELINE_SCHEDULE_DESCRIPTION	Pre-pipeline	The description of the pipeline schedule. Available only in scheduled pipelines. Introduced in GitLab 17.8.

Variable	Scope	Description
CI_PROJECT_ID	Pre-pipeline	The ID of the current project. This ID is unique across all projects in the GitLab instance.
CI_PROJECT_NAME	Pre-pipeline	The name of the project directory. For example, if the project URL is gitlab.example.com/group-name/project-1, CI_PROJECT_NAME is project-1.
CI_PROJECT_NAMESPACE	Pre-pipeline	The project namespace (username or group name) of the job.
CI_PROJECT_NAMESPACE_ID	Pre-pipeline	The project namespace ID of the job. Introduced in GitLab 15.7.
CI_PROJECT_NAMESPACE_SLUG	Pre-pipeline	Lowercase version of $CI_PROJECT_NAMESPACE, with characters that are not a-z or 0-9 replaced by - and truncated to 63 bytes.
CI_PROJECT_PATH_SLUG	Pre-pipeline	Lowercase version of $CI_PROJECT_PATH, with characters that are not a-z or 0-9 replaced by - and truncated to 63 bytes. Used for URLs and domain names.
CI_PROJECT_PATH	Pre-pipeline	The project namespace including the project name.
CI_PROJECT_REPOSITORY_LANGUAGES	Pre-pipeline	A comma-separated, lowercase list of languages used in the repository. For example, ruby,javascript,html,css. The maximum number of languages is limited to 5. There is an issue proposing to increase this limit.
CI_PROJECT_ROOT_NAMESPACE	Pre-pipeline	The root project namespace (username or group name) of the job. For example, if CI_PROJECT_NAMESPACE is root-group/child-group/grandchild-group, CI_PROJECT_ROOT_NAMESPACE is root-group.
CI_PROJECT_TITLE	Pre-pipeline	The human-readable project name displayed in the GitLab Web interface.
CI_PROJECT_DESCRIPTION	Pre-pipeline	The project description displayed in the GitLab Web interface. Introduced in GitLab 15.1.
CI_PROJECT_URL	Pre-pipeline	The HTTP(S) URL of the project.
CI_PROJECT_VISIBILITY	Pre-pipeline	Project visibility. Can be internal, private, or public.
CI_PROJECT_CLASSIFICATION_LABEL	Pre-pipeline	The project's external authorization classification label.

Variable	Scope	Description
CI_REGISTRY	Pre-pipeline	The URL of the container registry server, in the format <host>[:<port>]. For example: registry.gitlab.example.com. Available only if the container registry is enabled for the GitLab instance.
CI_REGISTRY_IMAGE	Pre-pipeline	The base URL of the container registry for pushing, pulling, or tagging project images, in the format <host>[:<port>]/<project_full_path>. For example: registry.gitlab.example.com/my_group/my_project. The image name must follow container registry naming conventions. Available only if the container registry is enabled for the project.
CI_REGISTRY_PASSWORD	Job-only	Password for pushing containers to the GitLab project's container registry. Available only if the container registry is enabled for the project. This password value is the same as CI_JOB_TOKEN and is valid only during the job execution. Use CI_DEPLOY_PASSWORD for long-term registry access.
CI_REGISTRY_USER	Job-only	Username for pushing containers to the project's GitLab container registry. Available only if the container registry is enabled for the project.
CI_TEMPLATE_REGISTRY_HOST	Pre-pipeline	The registry host used by CI/CD templates. Defaults to registry.gitlab.com. Introduced in GitLab 15.3.

Variable	Scope	Description
CI_RUNNER_DESCRIPTION	Job-only	The description of the runner.
CI_RUNNER_EXECUTABLE_ARCH	Job-only	The OS/architecture of the GitLab Runner executable. May differ from the executor's environment.
CI_RUNNER_ID	Job-only	The unique ID of the runner being used.
CI_RUNNER_REVISION	Job-only	The revision of the runner executing the job.
CI_RUNNER_SHORT_TOKEN	Job-only	The unique ID of the runner, used to authenticate new job requests. The token includes a prefix; use the first 17 characters.
CI_RUNNER_TAGS	Job-only	A JSON array of runner tags. For example ["tag_1", "tag_2"].
CI_RUNNER_VERSION	Job-only	The version of the GitLab Runner executing the job.
CI_SHARED_ENVIRONMENT	Pipeline	Available only if the job runs in a shared environment (an environment that persists between CI/CD invocations, such as shell or ssh executors). true when available.

Variable	Scope	Description
CI_SERVER_FQDN	Pre-pipeline	The Fully Qualified Domain Name (FQDN) of the instance. For example gitlab.example.com:8080. Introduced in GitLab 16.10.
CI_SERVER_HOST	Pre-pipeline	The host of the GitLab instance URL, excluding the protocol or port. For example gitlab.example.com.
CI_SERVER_NAME	Pre-pipeline	The name of the CI/CD server coordinating the job.
CI_SERVER_PORT	Pre-pipeline	The port of the GitLab instance URL, excluding the host or protocol. For example 8080.
CI_SERVER_PROTOCOL	Pre-pipeline	The protocol of the GitLab instance URL, excluding the host or port. For example https.
CI_SERVER_SHELL_SSH_HOST	Pre-pipeline	The SSH host of the GitLab instance, used for accessing Git repositories via SSH. For example gitlab.com. Introduced in GitLab 15.11.
CI_SERVER_SHELL_SSH_PORT	Pre-pipeline	The SSH port of the GitLab instance, used for accessing Git repositories via SSH. For example 22. Introduced in GitLab 15.11.
CI_SERVER_REVISION	Pre-pipeline	The GitLab revision that scheduled the job.
CI_SERVER_TLS_CA_FILE	Pipeline	File containing the TLS CA certificate, used to verify the GitLab server when tls-ca-file is set in the runner configuration.
CI_SERVER_TLS_CERT_FILE	Pipeline	File containing the TLS certificate, used to verify the GitLab server when tls-cert-file is set in the runner configuration.
CI_SERVER_TLS_KEY_FILE	Pipeline	File containing the TLS key, used to verify the GitLab server when tls-key-file is set in the runner configuration.
CI_SERVER_URL	Pre-pipeline	The base URL of the GitLab instance, including the protocol and port. For example https://gitlab.example.com:8080.
CI_SERVER_VERSION_MAJOR	Pre-pipeline	The major version of the GitLab instance. For example, if the GitLab version is 17.2.1, CI_SERVER_VERSION_MAJOR is 17.
CI_SERVER_VERSION_MINOR	Pre-pipeline	The minor version of the GitLab instance. For example, if the GitLab version is 17.2.1, CI_SERVER_VERSION_MINOR is 2.
CI_SERVER_VERSION_PATCH	Pre-pipeline	The patch version of the GitLab instance. For example, if the GitLab version is 17.2.1, CI_SERVER_VERSION_PATCH is 1.
CI_SERVER_VERSION	Pre-pipeline	The full version of the GitLab instance.
CI_SERVER	Job-only	Available in all CI/CD jobs. Set to yes when available.

Variable	Scope	Description
CI_TRIGGER_SHORT_TOKEN	Job-only	The first 4 characters of the trigger token for the current job. Available only if the pipeline was triggered by a trigger token. For example, for trigger token glptt-1234567890abcdefghij, CI_TRIGGER_SHORT_TOKEN is 1234. Introduced in GitLab 17.0.
GITLAB_USER_EMAIL	Pipeline	The email of the user who started the pipeline, unless the job is a manual job. In a manual job, the value is the email of the user who started the job.
GITLAB_USER_ID	Pipeline	The numeric ID of the user who started the pipeline, unless the job is a manual job. In a manual job, the value is the ID of the user who started the job.
GITLAB_USER_LOGIN	Pipeline	The unique username of the user who started the pipeline, unless the job is a manual job. In a manual job, the value is the username of the user who started the job.
GITLAB_USER_NAME	Pipeline	The display name of the user who started the pipeline (the full name defined in the user's profile settings), unless the job is a manual job. In a manual job, the value is the name of the user who started the job.
TRIGGER_PAYLOAD	Pipeline	Webhook data payload. Available only when the pipeline is triggered using a webhook.

Variable	Description
CI_MERGE_REQUEST_APPROVED	Approval status of the merge request. true when merge request approval is available and the merge request has been approved.
CI_MERGE_REQUEST_ASSIGNEES	Comma-separated list of usernames of the merge request assignees. Available only if the merge request has at least one assignee.
CI_MERGE_REQUEST_DIFF_BASE_SHA	The base SHA of the merge request diff.
CI_MERGE_REQUEST_DIFF_ID	The version of the merge request diff.
CI_MERGE_REQUEST_EVENT_TYPE	The event type of the merge request. Can be detached, merged_result, or merge_train.
CI_MERGE_REQUEST_DESCRIPTION	The description of the merge request. If the description length exceeds 2700 characters, only the first 2700 characters are stored in the variable. Introduced in GitLab 16.7.
CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED	true if CI_MERGE_REQUEST_DESCRIPTION was truncated to 2700 characters because the merge request description was too long, false otherwise. Introduced in GitLab 16.8.
CI_MERGE_REQUEST_ID	The instance-level ID of the merge request. This ID is unique across all projects in the GitLab instance.
CI_MERGE_REQUEST_IID	The project-level IID (internal ID) of the merge request. This ID is unique within the current project and is the number used in the merge request URL, page title, and other visible locations.
CI_MERGE_REQUEST_LABELS	Comma-separated list of label names for the merge request. Available only if the merge request has at least one label.
CI_MERGE_REQUEST_MILESTONE	The milestone title of the merge request. Available only if a milestone is set for the merge request.
CI_MERGE_REQUEST_PROJECT_ID	The project ID of the merge request.
CI_MERGE_REQUEST_PROJECT_PATH	The project path of the merge request. For example namespace/awesome-project.
CI_MERGE_REQUEST_PROJECT_URL	The project URL of the merge request. For example http://192.168.10.15:3000/namespace/awesome-project.
CI_MERGE_REQUEST_REF_PATH	The reference path of the merge request. For example refs/merge-requests/1/head.
CI_MERGE_REQUEST_SOURCE_BRANCH_NAME	The source branch name of the merge request.
CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED	true when the merge request's source branch is protected. Introduced in GitLab 16.4.
CI_MERGE_REQUEST_SOURCE_BRANCH_SHA	The HEAD SHA of the merge request's source branch. In merge request pipelines, the variable is empty. The SHA appears only in merged result pipelines.
CI_MERGE_REQUEST_SOURCE_PROJECT_ID	The source project ID of the merge request.
CI_MERGE_REQUEST_SOURCE_PROJECT_PATH	The source project path of the merge request.
CI_MERGE_REQUEST_SOURCE_PROJECT_URL	The source project URL of the merge request.
CI_MERGE_REQUEST_SQUASH_ON_MERGE	true when the squash on merge option is set. Introduced in GitLab 16.4.
CI_MERGE_REQUEST_TARGET_BRANCH_NAME	The target branch name of the merge request.
CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED	true when the merge request's target branch is protected. Introduced in GitLab 15.2.
CI_MERGE_REQUEST_TARGET_BRANCH_SHA	The HEAD SHA of the merge request's target branch. In merge request pipelines, the variable is empty. The SHA appears only in merged result pipelines.
CI_MERGE_REQUEST_TITLE	The title of the merge request.
CI_MERGE_REQUEST_DRAFT	true if the merge request is a draft. Introduced in GitLab 17.10.

Variable	Description
CI_EXTERNAL_PULL_REQUEST_IID	Pull request ID from GitHub.
CI_EXTERNAL_PULL_REQUEST_SOURCE_REPOSITORY	The source repository name of the pull request.
CI_EXTERNAL_PULL_REQUEST_TARGET_REPOSITORY	The target repository name of the pull request.
CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME	The source branch name of the pull request.
CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_SHA	The HEAD SHA of the pull request's source branch.
CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME	The target branch name of the pull request.
CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_SHA	The HEAD SHA of the pull request's target branch.
CI_EXTERNAL_PULL_REQUEST_LABELS	Comma-separated list of labels for the pull request. Available only if the merge request has at least one label.
CI_EXTERNAL_PULL_REQUEST_TITLE	The title of the pull request.
CI_EXTERNAL_PULL_REQUEST_DESCRIPTION	The description of the pull request.
CI_EXTERNAL_PULL_REQUEST_HTML_URL	The HTML URL of the pull request.

Integration Variables

The following integration variables are available in jobs as "job-only" predefined variables:

Harbor

Variable	Description
HARBOR_URL	URL of the Harbor instance.
HARBOR_HOST	Hostname of the Harbor instance.
HARBOR_OCI	Harbor OCI connection settings.
HARBOR_PROJECT	Target Harbor project name.
HARBOR_USERNAME	Harbor authentication username.
HARBOR_PASSWORD	Harbor authentication password.

Apple App Store Connect

Variable	Description
APP_STORE_CONNECT_API_KEY_ISSUER_ID	Apple App Store Connect API key issuer ID.
APP_STORE_CONNECT_API_KEY_KEY_ID	Apple App Store Connect API key ID.
APP_STORE_CONNECT_API_KEY_KEY	Apple App Store Connect API key content.
APP_STORE_CONNECT_API_KEY_IS_KEY_CONTENT_BASE64	Indicates whether the API key content is Base64 encoded.

Google Play

Variable	Description
SUPPLY_PACKAGE_NAME	Package name of the Android application.
SUPPLY_JSON_KEY_DATA	JSON key data for Google Play API access.

Diffblue Cover

Variable	Description
DIFFBLUE_LICENSE_KEY	License key for Diffblue Cover.
DIFFBLUE_ACCESS_TOKEN_NAME	Diffblue access token name.
DIFFBLUE_ACCESS_TOKEN	Diffblue access token.

Changelog

2025-04-07 Initial document creation.

On this page

GitLab CI Syntax and Variables Guide

Basic Structure

Stages

Jobs

Rules

Only/Except

Variables

Before Script / After Script

Cache

Artifacts

Dependencies

Workflow

Basic Syntax

Naming the Pipeline

Rule Conditions

Practical Examples

Notes

Needs

Services

Includes

Templates

Predefined Environment Variables List

Scope Description

ChatOps and Basic CI Variables

Integration Variables

Harbor

Apple App Store Connect

Google Play

Diffblue Cover

Changelog

Tags

CloudyWing's Note

Quick Links

Contact

On this page

GitLab CI Syntax and Variables Guide ​

Basic Structure ​

Stages ​

Jobs ​

Rules ​

Only/Except ​

Variables ​

Before Script / After Script ​

Cache ​

Artifacts ​

Dependencies ​

Workflow ​

Basic Syntax ​

Naming the Pipeline ​

Rule Conditions ​

Practical Examples ​

Notes ​

Needs ​

Services ​

Includes ​

Templates ​

Predefined Environment Variables List ​

Scope Description ​

ChatOps and Basic CI Variables ​

Commit-related Variables ​

Configuration and Path-related Variables ​

Dependency Proxy-related Variables ​

Deployment and Environment-related Variables ​

Job-related Variables ​

Pages-related Variables ​

Pipeline-related Variables ​

Project-related Variables ​

Container Registry-related Variables ​

Runner-related Variables ​

Server-related Variables ​

Trigger and User-related Variables ​

Merge Request-related Variables ​

External Request-related Variables ​

Integration Variables ​

Harbor ​

Apple App Store Connect ​

Google Play ​

Diffblue Cover ​

Changelog ​

Tags

Related Notes

Setting up GitLab as a NuGet Package Source in Visual Studio

How to Use GitLab CI in Docker

A Brief Discussion on the Differences Between Git Merge and Rebase

A Brief Introduction to Git Data Structures

CloudyWing's Note

Quick Links

Contact

GitLab CI Syntax and Variables Guide

Basic Structure

Stages

Jobs

Rules

Only/Except

Variables

Before Script / After Script

Cache

Artifacts

Dependencies

Workflow

Basic Syntax

Naming the Pipeline

Rule Conditions

Practical Examples

Notes

Needs

Services

Includes

Templates

Predefined Environment Variables List

Scope Description

ChatOps and Basic CI Variables

Commit-related Variables

Configuration and Path-related Variables

Dependency Proxy-related Variables

Deployment and Environment-related Variables

Job-related Variables

Pages-related Variables

Pipeline-related Variables

Project-related Variables

Container Registry-related Variables

Runner-related Variables

Server-related Variables

Trigger and User-related Variables

Merge Request-related Variables

External Request-related Variables

Integration Variables

Harbor

Apple App Store Connect

Google Play

Diffblue Cover

Changelog